Перейти к содержанию

Интерфейс RPC API

В данном документе описан Интерфейс RPC API — основной интерфейс взаимодействия с инстансом Picodata. Вызов RPC-функций происходит по протоколу iproto через коннектор net.box или любой другой.

RPC API используется в следующих сценариях:

  • Внешние системы могут вызывать функции через коннектор
  • Инстансы взаимодействуют друг с другом под служебной учетной записью pico_service
  • Тестирование pytest использует для подключения клиент tarantool-python
  • Подключение picodata connect использует вызов .proc_sql

Детали реализации

Функции RPC API представляют собой хранимые процедуры Tarantool box.func. Аргументы и возвращаемые значения функций описаны в системе типов msgpack.

Особенности энкодинга

  • optional поле (например optional MP_INT) отличается от обычного тем, что на его месте может присутствовать как ожидаемый msgpack тип (MP_INT), так и MP_NIL. Тем не менее, при формировании запроса, нельзя пропускать это поле. При отсутсвии значения, всегда должен быть указан MP_NIL

  • в случае успешного выполнения RPC фунцкии (IPROTO_OK) возвращаемое msgpack значение всегда дополнительно обёрнуто в MP_ARRAY

  • в случае ошибки выполения RPC функции (Result::Err в терминах Rust) в ответе будет iproto сообщение с типом IPROTO_TYPE_ERROR содержащее в себе описание
    ошибки

Привилегии

Хранимые процедуры Tarantool не входят в модель управления доступом Picodata. На них невозможно выдать или отозвать привилегии. Авторизация запросов происходит по следующему принципу:

  • функции public доступны для роли public, которая автоматически выдается всем новым пользователям. В этом случае авторизуется не вызов функции, а сам запрос

  • привилегиями на вызов остальных функций обладают Администратор СУБД (admin) и служебная учетная запись pico_service

Public API

.proc_version_info

fn proc_version_info() -> VersionInfo

Возвращает информацию о версиях Picodata и отдельных ее компонентах.

Возвращаемое значение:

  • (MP_MAP VersionInfo)

    • picodata_version: (MP_STR) версия Picodata
    • rpc_api_version: (MP_STR) версия RPC API согласно семантическому версионированию (Semantic Versioning)

.proc_sql

fn proc_sql(query, options) -> Result

Выполняет распределенный SQL-запрос.

Аргументы:

  • query: (MP_STR) запрос SQL
  • options: (optional MP_MAP) TODO

Возвращаемое значение:

  • (MP_MAP DqlResult) при чтении данных
    Поля:

    • metadata (MP_ARRAY), массив описаний столбцов таблицы в формате MP_ARRAY [ MP_MAP { name = MP_STR, type = MP_STR }, ...]
    • rows (MP_ARRAY), результат выполнения читающего запроса в формате MP_ARRAY [ MP_ARRAY row, ...]

  • (MP_MAP DmlResult) при модификации данных
    Поля:

    • row_count (MP_INT), количество измененных строк

См. также:

Service API

.proc_raft_info

fn proc_raft_info() -> RaftInfo

Возвращает информацию о состоянии raft-узла на текущем инстансе

Возвращаемое значение:

  • (MP_MAP RaftInfo)

    • id: (MP_INT) raft_id текущего узла
    • term: (MP_INT) текущий терм
    • applied: (MP_INT) текущий примененный индекс raft-журнала
    • leader_id: (MP_INT) raft_id лидера или 0 если в текущем терме его нет
    • state (MP_STR)
      возможные значения: Follower, Candidate, Leader, PreCandidate

.proc_instance_info

fn proc_instance_info(instance_id) -> InstanceInfo

Возвращает информацию о запрашиваемом инстансе из кластера.

При вызове без параметров возвращает информацию о текущем инстансе.

Аргументы:

  • instance_id: (optional MP_STR)

Возвращаемое значение:

  • (MP_MAP InstanceInfo)
    • raft_id: (MP_UINT)
    • advertise_address: (MP_STR)
    • instance_id: (MP_STR)
    • instance_uuid: (MP_STR)
    • replicaset_id: (MP_STR)
    • replicaset_uuid: (MP_STR)
    • cluster_id: (MP_STR)
    • current_grade: (MP_MAP Grade), текущее состояние инстанса
      формат: MP_MAP { variant = MP_STR, incarnation = MP_UINT}
      возможные значения variant: Offline, Replicated, Online, Expelled
    • target_grade: (MP_MAP Grade), целевое состояние инстанса
    • tier: (MP_STR)

.proc_runtime_info

fn proc_runtime_info() -> RuntimeInfo

Возвращает служебную информацию.

Возвращаемое значение:

  • (MP_MAP RuntimeInfo)
    • raft: (MP_MAP RaftInfo)
    • version_info: (MP_MAP VersionInfo)
    • internal: (MP_MAP)
      формат: MP_MAP { main_loop_status = MP_STR, governor_loop_status = MP_STR}
    • http: (optional MP_MAP HttpInfo)
      формат: MP_MAP { host = MP_STR, port = MP_UINT}
      поле отсутствует в ответе если инстанс запущен без параметра picodata run --http-listen

.proc_raft_promote

fn proc_raft_promote()

Завершает текущий raft-терм и объявляет выборы нового лидера. Предлагает себя как кандидата в лидеры raft-группы. Если других кандидатов не обнаружится, текущий инстанс с большой вероятностью станет новым лидером.

.proc_get_index

fn proc_get_index() -> RaftIndex

Возвращает текущий примененный (applied) индекс raft-журнала

Возвращаемое значение: MP_INT

.proc_read_index

fn proc_read_index(timeout) -> RaftIndex

Выполняет кворумное чтение по следующему принципу:

  1. Инстанс направляет запрос (MsgReadIndex) лидеру raft-группы. В случае, если лидера в данный момент нет, функция возвращает ошибку 'raft: proposal dropped'
  2. Raft-лидер запоминает текущий commit_index и отправляет всем узлам в статусе follower сообщение (heartbeat) с тем, чтобы убедиться, что он все еще является лидером
  3. Как только получение этого сообщения подтверждается большинством follower-узлов, лидер возвращает этот индекс инстансу
  4. Инстанс дожидается применения (apply) указанного raft-индекса. Если таймаут истекает раньше, функция возвращает ошибку 'timeout'

Параметры:

  • timeout: (MP_INT | MP_FLOAT) в секундах

Возвращаемое значение: MP_INT

.proc_wait_index

fn proc_wait_index(target, timeout) -> RaftIndex

Ожидает применения (apply) указанного raft-индекса на текущем инстансе. Функция возвращает текущий примененный индекс raft-журнала, который может быть равен или превышать указанный.

Параметры:

  • target: (MP_INT)
  • timeout: (MP_INT | MP_FLOAT) в секундах

Возвращаемое значение: MP_INT

.proc_get_vclock

fn proc_get_vclock() -> Vclock

Возвращает текущее значение Vclock

Возвращаемое значение: MP_MAP Vclock

.proc_wait_vclock

fn proc_wait_vclock(target, timeout) -> Vclock

Ожидает момента, когда текущее значение Vclock достигнет заданного. Возвращает текущее значение Vclock, которое может быть равно или превышать указанное.

Параметры:

  • target: (MP_MAP Vclock)
  • timeout: (MP_FLOAT) в секундах

Возвращаемое значение: MP_MAP Vclock

.proc_apply_schema_change

fn proc_apply_schema_change(raft_term, raft_index, timeout) -> Result

Дожидается момента, когда raft применит запись с заданным индексом и термом перед тем как делать что-то еще, чтобы синхронизировать состояние глобальных системных таблиц. Возвращает ошибку, если времени не хватило.

Применяет текущие изменения глобальной схемы к локальному состоянию инстанса.

Этy хранимую процедуру вызывает только governor в рамках алгоритма отказоустойчивой смены кластерной схемы данных.

Текущие изменения схемы инстанс читает из системной таблицы _pico_property. В ней по ключам pending_schema_change и pending_schema_version соответственно находятся описание текущей DDL-операции и версия глобальной схемы после применения этой операции.

В случае если изменение не применимо на текущем инстансе из-за конфликта хранимых данных, в ответ посылается сообщение с причиной конфликта.

Параметры:

  • raft_term: (MP_INT)
  • raft_index: (MP_INT)
  • timeout: (MP_INT | MP_FLOAT) в секундах

Возвращаемое значение:

  • (MP_STR Ok)
  • (MP_MAP, { "Abort": { "reason": MP_STR } }) в случае ошибки

.proc_replication

fn proc_replication(is_master, replicaset_peers) -> Lsn

Обновляет конфигурацию топологии репликации текущего инстанса с остальными инстансами из одного репликасета.

Данную хранимую процедуру вызывает только governor в рамках алгоритма автоматической смены топологии кластера.

Первоисточником принадлежности инстанса к тому или иному репликасету является информация в системной таблице _pico_instance, однако при вызове этой хранимой процедуры список адресов инстансов указывается явно из-за ограничений на репликацию системных таблиц: так как данные системных таблиц распространяются через механизм репликации, его нужно настроить перед тем, как данные смогут реплицироваться.

Для репликации Picodata использует топологию full-mesh, при которой каждая реплика поддерживает соединение с каждой другой репликой. При этом, мастер-реплика в каждом репликасете только одна. Признак того, что текущая реплика должна стать мастером, передается соответствующим параметром.

См. также:

В случае успешного завершения в ответ посылается LSN текущего инстанса. Эта информация на данный момент используется только для отладки.

Параметры:

  • is_master: (MP_BOOL)
  • replicaset_peers: (MP_ARRAY of MP_STR)

Возвращаемое значение:

  • (MP_INT)

.proc_replication_promote

fn proc_replication_promote(vclock, timeout)

Переводит текущий инстанс в состояние мастер-реплики предварительно синхронизируя его с остальными репликами.

Данную хранимую процедуру вызывает только governor в рамках алгоритма автоматической смены текущего мастера репликасета.

См. также:

Получив такой запрос, инстанс дожидается пока его локальный vclock не догонит vclock предыдущей мастер-реплики (указан в параметрах) или не закончится отведенное на это время. Vclock предыдущего мастера governor получает после вызова на ней [#proc_replication_demote].

Синхронизация происходит в фоновом режиме за счет механизма репликации. Смотри [#proc_replication] о том, как в Picodata настраивается репликация.

Параметры:

  • vclock: (MP_MAP Vclock)
  • timeout: (MP_INT | MP_FLOAT) в секундах

.proc_replication_demote

fn proc_replication_demote() -> Vclock

Переводит текущий инстанс в состояние резервной реплики.

Данную хранимую процедуру вызывает только governor в рамках алгоритма автоматической смены текущего мастера репликасета.

См. также:

Получив такой запрос, инстанс сразу переходит в режим read-only и отправляет в ответ текущее значение своего vclock, которое дальше используется для синхронизации новой мастер-реплики (см. [#proc_replication_promote]).

См. [#proc_replication] о том, как в Picodata настраивается репликация.

Параметры:

  • vclock: (MP_MAP ключ: MP_INT, значение: MP_INT)
  • timeout: (MP_INT | MP_FLOAT) в секундах

Возвращаемое значение:

  • (MP_MAP Vclock)

.proc_sharding

fn proc_sharding(raft_term, raft_index, timeout, do_reconfigure)

Дожидается применения raft записи с заданным индексом и термом перед тем как делать что-то еще, чтобы синхронизовать состояние глобальных системных таблиц. Возвращает ошибку, если времени не хватило.

Обновляет конфигурацию шардирования данных между репликасетами.

Этy хранимую процедуру вызывает только governor в рамках алгоритма автоматической смены топологии кластера

См. также:

Конфигурация распределения бакетов хранится в системной таблице _pico_property по ключу target_vshard_config.

Параметр do_reconfigure указывает, нужно ли обновлять конфигурацию в случае если она уже применена на текущем инстансе, о чем говорит наличие Lua-переменной pico._vshard_is_configured.

Параметры:

  • raft_term: (MP_INT)
  • raft_index: (MP_INT)
  • timeout: (MP_INT | MP_FLOAT) в секундах
  • do_reconfigure (MP_BOOL)

.proc_sharding_bootstrap

fn proc_sharding_bootstrap(raft_term, raft_index, timeout)

Дожидается применения raft записи с заданным индексом и термом перед тем как делать что-то еще, чтобы синхронизовать состояние глобальных системных таблиц. Возвращает ошибку, если времени не хватило.

Инициирует распределение бакетов между репликасетами.

Этy хранимую процедуру вызывает только governor в рамках алгоритма автоматической смены топологии кластера.

См. также:

За жизненный цикл кластера эта процедура вызывается ровно один раз, как только в кластере появляется первый репликасет, удовлетворяющий соответствующему фактору репликации.

Параметры:

  • raft_term: (MP_INT)
  • raft_index: (MP_INT)
  • timeout: (MP_INT | MP_FLOAT) в секундах

.proc_raft_snapshot_next_chunk

fn proc_raft_snapshot_next_chunk(raft_term, raft_index, snapshot_position)

Возвращает следующий отрезок данных raft-снапшота.

Этy хранимую процедуру вызывают только инстансы с ролью raft follower в рамках процесса актуализации raft-журнала.

Текущий инстанс проверяет наличие снапшота соответствующего состоянию raft-журнала на момент, когда актуальными были указанные терм и индекс. При этом, снапшот должен существовать на момент вызова этой процедуры, так как он создается автоматически когда raft-лидер получает запрос на актуализацию raft-журнала и обнаруживает, что его журнал был компактизирован.

Снапшот представляет из себя последовательность кортежей глобальных таблиц, как системных так и пользовательских. В этой последовательности кортежи сгруппированы по таблицам и упорядочены в соответствие с первичными ключами таблиц. Последовательность таблиц в снапшоте детерминирована и совпадает между разными версиями снапшотов.

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

Параметры:

  • raft_term: (MP_INT)
  • raft_index: (MP_INT)
  • snapshot_position: (MP_MAP SnapshotPosition)
    • table_id: MP_INT
    • tuple_offset: MP_INT

Возвращаемое значение:

  • (MP_MAP SnapshotData)

    • schema_version: MP_INT

    • space_dumps: MP_ARRAY:

      • MP_MAP:
        • table_id: MP_INT
        • tuples: MP_ARRAY of MP_ARRAY "сырые" кортежи таблицы

    • next_position: MP_NIL | MP_MAP SnapshotPosition (см. выше)

.proc_cas

fn proc_cas(cluster_id, predicate, op, as_user) -> (RaftIndex, RaftTerm)

Выполняется только на raft-лидере, в противном случае немедленно возвращает ошибку.

Исполняет кластерную операцию compare-and-swap.

Проверяет предикат. Если проверка не выявляет конфликтов, то добавляет новую запись в raft-журнал и возвращает ее индекс (пока еще не зафиксированный в кластере). Операция применяется только для глобальных таблиц и работает на всем кластере.

Предикат состоит из трех частей:

  • индекс записи в raft-журнале;
  • номера терма;
  • диапазона значений самого проверяемого параметра (ranges).

Параметры:

  • cluster_id: (MP_STR)
  • predicate: (MP_MAP CasPredicate)
  • op: (MP_MAP Op)
  • as_user: (MP_INT)

Возвращаемое значение:

  • (MP_INT raft индекс)
  • (MP_INT raft терм)

.proc_raft_interact

fn proc_raft_interact(raft_messages)

Этy хранимую процедуру вызывают все инстансы Picodata для передачи внутренних сообщений друг другу в рамках реализации алгоритма raft.

Параметры:

  • raft_messages: (MP_ARRAY of MP_ARRAY)

.proc_discover

fn proc_discover(request, receiver)

Этy хранимую процедуру вызывают инстансы Picodata во время запуска с пустым состоянием (bootstrap) в рамках реализации алгоритма discovery.

Параметры:

  • request: (MP_MAP):
    • tmp_id: (MP_STR)
    • peers: (MP_ARRAY of MP_STR)
  • receiver: (MP_STR) адрес, по которому доступен текущий инстанс

Возвращаемое значение:

  • (MP_MAP)

    • LeaderElection: (MP_MAP) в случае если алгоритм продолжается

      • tmp_id: (MP_STR)
      • peers: (MP_ARRAY of MP_STR)

    • Done: (MP_MAP): в случае если результат уже известен

      • leader_address: (MP_STR): адрес лидера

.proc_raft_join

fn proc_raft_join(cluster_id, instance_id, replicaset_id, advertise_address, failure_domain, tier)

Выполняется только на raft-лидере, в противном случае немедленно возвращает ошибку.

Этy хранимую процедуру вызывают инстансы Picodata, присоединяющиеся к кластеру, то есть еще не состоящие в raft-группе.

См. также:

Параметры:

  • cluster_id: (MP_STR),
  • instance_id: (MP_STR | MP_NIL),
  • replicaset_id: (MP_STR | MP_NIL) идентификатор репликасета,
  • advertise_address: (MP_STR),
  • failure_domain: (MP_MAP) домен отказа,
  • tier: (MP_STR) идентификатор тира,

Возвращаемое значение:

  • instance: (MP_MAP): кортеж из системной таблицы _pico_instance, соответствующий присоединяющемуся инстансу,

  • peer_addresses: (MP_ARRAY): набор адресов некоторых инстансов кластера

    • (MP_MAP):
      • raft_id: (MP_INT),
      • address: (MP_STR),

  • box_replication: (MP_ARRAY of MP_STR): адреса всех реплик в репликасете присоединяющегося инстанса

.proc_update_instance

fn proc_update_instance(instance_id, cluster_id, current_grade, target_grade, failure_domain, dont_retry)

Выполняется только на raft-лидере, в противном случае немедленно возвращает ошибку.

Обновляет информацию об указанном инстансе.

Этy хранимую процедуру вызывают инстансы Picodata, уже состоящие в кластере, чтобы обновить свое целевое состояние при перезапуске или в рамках штатного выключения.

Лидер, получив такой запрос, проверяет консистентность параметров (например, что новый домен отказа не противоречит конфигурации репликасета), и выполняет CaS-операцию по применению изменений к глобальной системной таблице _pico_instance.

По умолчанию, если в raft-журнал попала конфликтующая CaS-операция, запрос повторяется.

Параметры:

  • instance_id: (MP_STR),
  • cluster_id: (MP_STR),
  • current_grade: (MP_MAP Grade), текущее состояние инстанса
  • target_grade: (MP_STR GradeVariant), целевое состояние инстанса
  • failure_domain: (MP_MAP) домен отказа,
  • dont_retry: (MP_BOOL), не повторять CaS запрос в случае конфликта

.proc_expel

fn proc_expel(cluster_id, instance_id)

Выполняется только на raft-лидере, в противном случае немедленно возвращает ошибку.

Удаляет указанный инстанс из кластера. На его место в будущем может прийти инстанс с тем же instance_id, однако raft_id уходящего инстанса больше никогда не будет использоваться.

Параметры:

  • cluster_id: (MP_STR),
  • instance_id: (MP_STR),

.proc_expel_redirect

fn proc_expel_redirect(cluster_id, instance_id)

Вызывает proc_expel на текущем raft-лидере.

Параметры:

  • cluster_id: (MP_STR),
  • instance_id: (MP_STR),