Расширение server-sent-events

Расширение Server Sent Events подключается к EventSource напрямую из HTML. Оно управляет подключениями к веб-серверу, прослушивает события сервера и затем в реальном времени вставляет их содержимое в страницу htmx.

SSE — это лёгкий альтернативный вариант WebSockets, работающий через существующие HTTP-соединения, поэтому его легко использовать через прокси-серверы и брандмауэры. Помните, что SSE — это однонаправленная служба, поэтому вы не можете отправлять сообщения на сервер SSE после установления подключения. Если вам нужна двунаправленная связь, то вам следует рассмотреть использование WebSockets вместо этого.

Это расширение заменяет экспериментальный hx-sse атрибут, встроенный в предыдущие версии htmx. Для помощи в миграции из более старых версий ознакомьтесь с руководством по миграции внизу этой страницы.

Используйте следующие атрибуты для настройки поведения соединений SSE:

• sse-connect="<url>" — URL сервера SSE.
• sse-swap="<message-name>" — имя сообщения, которое нужно вставить в DOM.
• hx-trigger="sse:<message-name>" — сообщения SSE также могут вызывать HTTP-обработчики с помощью атрибута hx-trigger.

Установка

<script src="https://unpkg.com/htmx.org/dist/ext/sse.js"></script>

Использование

  <div hx-ext="sse" sse-connect="/chatroom" sse-swap="message">
      Contents of this box will be updated in real time
      with every SSE message received from the chatroom.
  </div>

Подключение к серверу SSE

Чтобы подключиться к серверу SSE, используйте атрибут hx-ext="sse", чтобы установить расширение на этот элемент HTML, а затем добавьте sse-connect="<url>" в элемент, чтобы установить соединение.

При проектировании вашего серверного приложения помните, что SSE работает так же, как любой HTTP-запрос. Хотя вы не можете отправлять сообщения на сервер после установления соединения, вы можете отправлять параметры на сервер вместе с запросом. Таким образом, вместо того, чтобы установить соединение SSE с сервером по адресу https://my-server/chat-updates, вы также можете подключиться к https://my-server/chat-updates?friends=true&format=detailed. Это позволяет вашему серверу настраивать свои ответы в соответствии с потребностями вашего клиента.

Получение событий с именами

Сообщения SSE состоят из имени события и пакета данных. Другая метаданные в сообщении не допускаются. Вот пример:

event: EventName
data: <div>Content to swap into your HTML page.</div>

Мы будем использовать атрибут sse-swap для прослушивания этого события и вставки его содержимого в нашу веб-страницу.

<div hx-ext="sse" sse-connect="/event-source" sse-swap="EventName"></div>

Обратите внимание, что имя EventName из сообщения сервера должно совпадать со значением в атрибуте sse-swap. Ваш сервер может использовать любое количество различных имён событий, но будьте осторожны: браузеры могут прослушивать только события, которые были явно названы. Таким образом, если ваш сервер отправляет событие с именем ChatroomUpdate, а ваш браузер прослушивает только события с именем ChatUpdate, то дополнительное событие будет проигнорировано.

Получение событий без имён

Сообщения SSE также могут быть отправлены без имени события. В этом случае браузер использует стандартное имя message вместо него. Те же правила, указанные выше, всё ещё действуют. Если ваш сервер отправляет безымянное сообщение, то вы должны прослушать его, включив sse-swap="message". Варианта использования универсального имени нет. Вот как это выглядит:

data: <div>Content to swap into your HTML page.</div>

<div hx-ext="sse" sse-connect="/event-source" sse-swap="message"></div>

Получение нескольких событий

Вы также можете прослушивать несколько событий (с именем или без) от одного EventSource. Прослушиватели должны быть либо 1) тем же элементом, который содержит атрибуты hx-ext и sse-connect, либо 2) дочерними элементами элемента, содержащего атрибуты hx-ext и sse-connect.

Multiple events in the same element
<div hx-ext="sse" sse-connect="/server-url" sse-swap="event1,event2"></div>
Multiple events in different elements (from the same source).
<div hx-ext="sse" sse-connect="/server-url">
    <div sse-swap="event1"></div>
    <div sse-swap="event2"></div>
</div>

Вызов обратных вызовов на сервере

После установления соединения для событий, отправляемых сервером, дочерние элементы могут прослушивать эти события, используя специальный синтаксис hx-trigger sse:<event_name>. Это, в сочетании с hx-get или аналогичным, заставит элемент выполнить запрос.

Вот пример:

  <div hx-ext="sse" sse-connect="/event_stream">
    <div hx-get="/chatroom" hx-trigger="sse:chatter">
      ...
    </div>
  </div>

Этот пример устанавливает соединение SSE с конечной точкой event_stream, которая затем вызывает GET по адресу /chatroom всякий раз, когда происходит событие chatter.

Автоматическое переподключение

Если поток событий SSE неожиданно закрывается, браузеры должны пытаться автоматически переподключиться. Однако в редких случаях это не работает, и ваш браузер может зависнуть. Это расширение добавляет свою собственную логику переподключения (используя алгоритм экспоненциального отката) поверх автоматического переподключения браузера, чтобы потоки SSE всегда были максимально надёжными.

Тестирование соединений SSE с сервером-демо

Htmx включает демо-сервер SSE, написанный на Node.js, который поможет вам увидеть SSE в действии и начать создание своего кода SSE. Он расположен в папке /test/ws-sse дистрибутива htmx. Обратитесь к файлу /test/ws-sse/README.md за инструкциями по запуску и использованию тестового сервера.

Миграция из предыдущих версий

Предыдущие версии htmx использовали встроенный тэг hx-sse для реализации Server Sent Events. Этот код был перенесён в расширение вместо этого. Вот шаги, которые вам нужно выполнить, чтобы перейти на эту версию:

Дополнительные ресурсы SSE

• Википедия
• MDN Web Docs
• Can I Use?