swm-uws: нативный uWebSockets binding для Node.js

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

Shellinstall

npm install @swarmmachina/swm-uws

JavaScriptquick-start.js

import uWS from '@swarmmachina/swm-uws'

const app = uWS.App()

app.get('/', (res) => {
  res.writeHeader('content-type', 'application/json')
    .end('{"ok":true}')
})

app.ws('/ws', {
  message(ws, message, isBinary) {
    ws.send(message, isBinary)
  }
})

app.listen(3000, (socket) => {
  if (!socket) process.exit(1)
})

Доступны default import, CommonJS require и named imports App / us_listen_socket_close.
app.close() идемпотентен и закрывает активные HTTP- и WebSocket-контексты.
Полная TypeScript-поверхность объявлена в lib/index.d.ts.

Поддерживаемая поверхность

HTTP routing: get, post, put, patch, del, options, head, connect, trace и any.
Streaming: write, tryEnd, onWritable, onData, collectBody, pause/resume и cork.
WebSocket: Lifecycle callbacks, send, fragmented sends, ping, topics и pub/sub.
Сетевые адреса: Remote и PROXY protocol addresses, ports, listen options и Unix sockets.
Опциональные fast paths: capabilities() сообщает endBatch, beginWrite, collectBody и другие доступные ускорения.
Явные границы: SSLApp/TLS, H3App, permessage-deflate, SNI и экспериментальные KV/timer helpers не реализованы.

Runtime и платформы

Среда	Статус	Примечание
Node.js 22 / 24	Поддерживается	Prebuilds выпускаются для поддерживаемых ABI.
Linux x64 + glibc	Поддерживается	Portable generic x86-64 build.
Windows x64	Поддерживается	Нативная сборка входит в пакет.
macOS arm64 / x64	Поддерживается	Apple Silicon и Intel.
Windows ARM64	Не поддерживается	Нет текущего prebuild.
Alpine / musl	Не поддерживается	Нужна glibc-среда.
TLS / permessage-deflate	Отключено	TLS завершается перед приложением.

Карта API

TemplatedApp

Маршруты, listen, WebSocket behavior и pub/sub.

get()post()put()patch()del()options()head()any()ws()publish()numSubscribers()listen()listen_unix()filter()close()

HttpRequest / HttpResponse

Данные запроса, snapshot и потоковый ответ.

getMethod()getUrl()getHeader()getQuery()getParameter()forEach()snapshot()writeStatus()writeHeader()end()write()tryEnd()onWritable()onData()collectBody()onAborted()

WebSocket

Сообщения, фрагменты, backpressure и темы.

send()sendFirstFragment()sendFragment()sendLastFragment()ping()publish()cork()end()close()getBufferedAmount()getRemoteAddress()getUserData()subscribe()unsubscribe()isSubscribed()getTopics()

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

Lifetime и владение памятью

Binding близок к нативному uWS, поэтому время жизни wrapper-объектов и буферов является частью API-контракта.

Snapshot перед await

HttpRequest действителен только внутри route/upgrade callback. Перед асинхронной работой вызовите req.snapshot(paramCount).

Нулевая копия требует дисциплины

onData и onDataV2 получают zero-copy ArrayBuffer, который отсоединяется после callback. Скопируйте chunk, если он нужен позже.

Owned body

collectBody(maxSize, callback) возвращает принадлежащий приложению ArrayBuffer или null при превышении лимита.

Продление жизни response

Response остаётся валиден после route callback только при регистрации onData, onWritable, collectBody или onAborted.

Callback завершения

Response и WebSocket wrappers уже недействительны внутри onAborted и close callback соответственно.

Drop-in alias для uWebSockets.js

Если приложение использует поддерживаемую обычную App() поверхность, пакет можно установить под исходным именем. Для SSLApp, H3App, compression, SNI и экспериментальных API нужна явная миграция.

Shellinstall alias

npm install uwebsockets.js@npm:@swarmmachina/swm-uws

JavaScriptserver.js

// Исходный import остаётся без изменений
import uWS from 'uwebsockets.js'

Нужны готовые HTTP-контексты, routing и graceful shutdown?Открыть swm-core