# Matcher WebSocket API

Matcher поддерживает протокол связи WebSocket (opens new window) и предоставляет WebSocket API. Протокол делает возможным более тесное взаимодействие между браузером и веб-сайтом, способствуя распространению интерактивного содержимого и созданию приложений реального времени. Большинство браузеров, например Google Chrome, Microsoft Edge, Internet Explorer, Firefox, Safari и Opera поддерживают данный протокол.

Сообщения, которые приходят от Matcher представлены в виде объектов JSON, которые могут содержать поля состоящие из букв или комбинаций букв, например "t", "Q". Данные поля предназначены для обработки Клиентом; JSON объекты могут содержать символы, например "%" или "_". Такие символы не рекомендуется использовать в Клиенте, так как они используются для внутренних нужд и могут измениться в любой момент. Тип сообщения содержится в поле "T".

# Базовые URL

MainNet: wss://matcher.waves.exchange/ws

TestNet: wss://matcher-testnet.waves.exchange/ws

# Терминология

snapshot - текущее состояние, которое отправляется только один раз, сразу после подключения через WebSocket.

updates - новое состояние, к которому пришел объект после каких-либо действий на Матчере. updates и snapshot имеют одинаковый формат полей, за исключением того, что updates содержит только обновленные поля. Клиент должен самостоятельно применять изменения из updates к объекту, чтобы получить актуальное состояние. Изменения должны применяться в порядке их получения.

domain message - сообщение, относящееся к сущностям, моделирующих доменную область, таким как ордер букам, адресам, и т.д.

system message - сообщение, которое относится к работе Matcher и требующее от Клиента специальных действий. Например, Ping требует ответа Pong. Оба этих сообщений - системные.

# Ping/Pong

Ping/pong это стрим системных сообщений, который позволяет понять работает ли подключение. Стрим также поддерживает соединение в работающем состоянии.

Алгоритм работы:

Раз в N секунд Matcher отправляет Ping с неким payload через соединение WebSocket;
Клиент должен в ответ прислать Pong с таким же payload;
Если Pong с таким же payload не приходит на Matcher через M секунд - Matcher прерывает соединение;
Matcher всегда ожидает сообщение Pong, содержащее такой же payload как в Ping и игнорирует Pong с неправильным payload;

Значение N и M задает Matcher.

Ping и Pong имеют одинаковый формат. Формат может меняться, но тип сообщение не может. Когда Клиент получает Ping, он должен отправить на Matcher такое же сообщение.

Ping/Pong реализован одинаково для всех стримов.

Пример:

{
  "T": "pp",
  "_": 1585148910776
}

В данном примере:

pp это тип сообщения Pong/Pong.

1585148910776 это Unix временная отметка обновления в миллисекундах. Данное поле предназначено для отладки.

# Частые вопросы (FAQ)

Q: Почему на используются Ping/Pong frames, которые описаны в RFC?

A: К сожалению, в реализации WebSocket для браузеров нет доступа к Control frames (opens new window).

Q: Почему Ping отправляет Matcher, а не Клиент?

A: Мы следуем рекомендациям спецификации (opens new window)

User agents must not use pings or unsolicited pongs to aid the server; it is assumed that servers will solicit pongs whenever appropriate for the server's needs.

См. также:

Ошибки и отладка

Common Streams