swm-core: HTTP и WebSocket сервер для Node.js

Установка и быстрый старт

Shellinstall

npm install @swarmmachina/swm-core

JavaScriptquick-start.js

import Server from '@swarmmachina/swm-core'

const server = new Server({
  port: 3000,
  http: {
    routes: [
      {
        method: 'get',
        path: '/health',
        handler: () => ({ ok: true })
      }
    ]
  },
  ws: {
    onMessage: (ctx, message, isBinary) => {
      ctx.send(message, isBinary)
    }
  }
})

await server.listen()

Синхронный handler оставляйте синхронным: Promise-путь нужен только при реальном await.
http.onRequest и http.routes взаимоисключающие. Пустой http: {} возвращает предсказуемый 404.
HTTP и WebSocket можно включать независимо; хотя бы один из них должен быть настроен.

Что предоставляет сервер

Нативный транспорт: HTTP и WebSocket проходят через @swarmmachina/swm-uws без промежуточного JS transport layer.
Два API маршрутизации: Универсальный onRequest или декларативные method/path routes с :param и wildcard /*.
Контроль памяти: Пулы HttpContext, отдельные лимиты HTTP/WS, maxBodyBudget и ленивое чтение body.
Потоки и backpressure: stream, startStreaming, tryEnd, onWritable и числовой статус отправки WebSocket.
Управление соединениями: Pub/sub, адресация через connectionKey, sendTo, graceful close и force terminate.
Завершение работы: shutdown(timeout) ждёт активные соединения; close() закрывает сервер немедленно.

Runtime и платформы

Среда	Статус	Примечание
Node.js 22 / 24	Поддерживается	Другие major-версии отклоняются engines constraint.
Linux x64 + glibc	Поддерживается	Для контейнеров используйте bookworm/slim.
Windows x64	Поддерживается	Готовая нативная сборка.
macOS arm64 / x64	Поддерживается	Apple Silicon и Intel.
Linux ARM64 / Windows ARM64	Нет сборки	Не входят в текущую матрицу prebuilds.
Alpine / musl	Не поддерживается	Используйте glibc-based image.
TLS / permessage-deflate	Отключено	Завершайте TLS перед приложением.

Карта API

Server

Жизненный цикл, pub/sub и адресуемые WebSocket-соединения.

listen()shutdown(timeout)close()publish(topic, message)getSubscribersCount(topic)sendTo(key, message)closeConnection(key)terminateConnection(key)hasConnection(key)getConnection(key)connectionCount

HttpContext

Данные запроса, ответ, body readers и потоковая передача.

method()url()ip()query(name)param(name)header(name)contentLength()body()buffer()json()text()status()setHeader()appendHeader()setHeaders()send()reply()stream()startStreaming()write()tryEnd()onWritable()

WSContext

Операции одного WebSocket-соединения.

datawskeysend()end()terminate()subscribe()unsubscribe()publish()decode()

Полные сигнатуры, типы и примеры находятся в README и TypeScript declarations исходного репозитория.

Body lifetime, лимиты и backpressure

swm-core намеренно оставляет стоимость и время жизни данных видимыми. Эти правила важны для корректного production-кода.

Lazy body до первого await

В режиме по умолчанию вызовите ctx.body(), buffer(), text() или json() до первой асинхронной операции. Иначе uWS-события body могут прийти до регистрации reader.

Prefetch для async auth

Включите prefetch глобально или для маршрута, если сначала нужно дождаться БД/авторизации, а затем читать body. Байты собираются заранее, JSON всё равно парсится лениво.

Ограничивайте совокупную память

maxBodySize ограничивает один запрос, maxBodyBudget - все одновременно собираемые body. Исчерпание бюджета даёт 503, превышение request limit - 413.

Проверяйте send status

WSContext.send() возвращает 1 при успехе, 0 при backpressure и 2, если сообщение отброшено из-за лимита.

Не удерживайте HttpContext

HttpContext переиспользуется между запросами. WSContext живёт всё соединение, но использовать его после onClose нельзя.

Когда брать низкоуровневый binding

swm-core подходит большинству сервисов. Переходите к swm-uws, если нужна прямая совместимость с обычным App() API uWebSockets.js и вы готовы сами управлять lifetime request/response объектов.

JavaScripttransport-choice.js

// Высокоуровневый сервер
import Server from '@swarmmachina/swm-core'

// Низкоуровневый binding
import uWS from '@swarmmachina/swm-uws'

Нужен низкоуровневый API uWebSockets.js без серверных абстракций?Открыть swm-uws