Что такое swm-uws?

swm-uws - экспериментальный non-TLS V8 binding для Node.js 22 и 24, совместимый с обычной поверхностью uWebSockets.js App(). Релиз 0.7.3 закрепляет uWebSockets.js 20.69.0, поставляет platform-specific prebuilds и не имеет runtime npm-зависимостей.

Можно ли использовать swm-uws как drop-in замену uWebSockets.js?

Да, для документированной non-TLS App() поверхности пакет можно установить alias-командой uwebsockets.js@npm:@swarmmachina/swm-uws. SSLApp, H3App, compression, SNI и экспериментальные upstream API не поддерживаются и требуют явной миграции.

Какие данные запроса можно использовать после callback?

Сам HttpRequest недействителен после route или upgrade callback, но строки из getMethod(), getUrl(), getQuery(), getHeader() и getParameter() принадлежат JavaScript и могут жить дольше. Для выбранных заголовков с сохранением duplicate/missing semantics создайте RequestPrefetchPlan и вызовите req.prefetch(plan) внутри callback.

Как настроить HTTP-лимиты и таймауты в swm-uws 0.7?

Передайте App({ http: { ... } }) с maxHeaderSize, maxHeaderCount, headersTimeoutMs, keepAliveTimeoutMs, bodyIdleTimeoutMs, minBodyRateBytesPerSec и responseWriteTimeoutMs. Счётчики отказов и activeConnections доступны через app.getHttpTransportStats().

Как pause/resume ограничивает upload в swm-uws 0.7.3?

res.pause() останавливает дальнейшее чтение сокета, когда consumer временно не готов к новым данным. Callback всё ещё может увидеть chunks из текущего parser buffer. Вызывайте res.resume() только после освобождения downstream-ёмкости: не вызванный resume больше не маскируется продолжением чтения и оставляет upload под backpressure.

Какие платформы и сетевые функции поддерживает swm-uws?

Поддерживаются Node.js 22/24, Linux x64 с glibc, Windows x64 и macOS arm64/x64. TLS/SSLApp, H3App, permessage-deflate, SNI, Alpine/musl, Linux ARM64 и Windows ARM64 не поддерживаются; TLS завершается перед приложением.

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)
  }
})

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

process.on('SIGTERM', () => {
  if (listenSocket) uWS.us_listen_socket_close(listenSocket)
  app.close()
})

Доступны default import, CommonJS require и named imports App / us_listen_socket_close.
app.close() идемпотентен и закрывает активные HTTP- и WebSocket-контексты.
Полная TypeScript-поверхность объявлена в lib/index.d.ts; defineHttpHandler и defineWebSocketBehavior типизируют вынесенные JavaScript callbacks.
В v0.7.3 res.pause() останавливает дальнейшее чтение сокета, чтобы медленный consumer не накапливал upload; res.resume() явно возобновляет доставку. Текущий parser buffer всё ещё может отдать уже принятые chunks.

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

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.
HTTP transport policy: Per-App лимиты заголовков, phase-specific timeouts, минимальная скорость body и getHttpTransportStats() для счётчиков.
Выборочный request prefetch: RequestPrefetchPlan нормализует список заголовков один раз, а req.prefetch() возвращает owned snapshot только выбранных полей.
Опциональные fast paths: capabilities() сообщает beginWrite, collectBody, httpTransportConfig, requestPrefetch, responseBatch и requestPause.
Контракты безопасности: Framing headers проверяются binding-ом, callback errors сохраняют исходное исключение, а WebSocket user data не может затереть методы wrapper-а.
Явные границы: 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.
Linux ARM64 / Windows ARM64	Не поддерживается	Нет текущих prebuilds.
Alpine / musl	Не поддерживается	Нужна glibc-среда.
TLS / permessage-deflate	Отключено	TLS завершается перед приложением.

Карта API

TemplatedApp

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

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

HttpRequest / HttpResponse

Owned request values, выборочный header prefetch и потоковый ответ.

getMethod()getCaseSensitiveMethod()getUrl()getHeader()getQuery()getParameter()forEach()prefetch(plan)writeStatus()writeHeader()end()write()tryEnd()onWritable()onData()onDataV2()collectBody()pause()resume()onAborted()

WebSocket

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

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

Module helpers

Типизация JavaScript callbacks, сведения о binding и управление listener.

defineHttpHandler()defineWebSocketBehavior()RequestPrefetchPlanversion()capabilities()us_listen_socket_close()

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

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

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

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

Wrapper действителен только внутри route/upgrade callback. Отдельные get* методы возвращают owned JavaScript strings; для выбранных заголовков с duplicate/missing semantics вызовите req.prefetch() с заранее созданным RequestPrefetchPlan.

Настраивайте transport на App

App({ http }) принимает лимиты заголовков, таймауты фаз и minimum body rate. getHttpTransportStats() отдаёт activeConnections и счётчики отказов без обхода соединений.

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

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

Pause требует resume

res.pause() останавливает дальнейшее чтение сокета, но callbacks могут получить chunks, уже находившиеся в текущем parser buffer. Возобновляйте res.resume() только когда consumer готов читать дальше; иначе upload останется под backpressure.

Owned body

collectBody(maxSize, callback) принимает лимит 0..1 ГиБ в байтах и возвращает принадлежащий приложению ArrayBuffer или null при превышении. Общий лимит памяти остаётся ответственностью приложения.

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

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

Callback завершения

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

Framing принадлежит binding

Content-Length и Transfer-Encoding устанавливают response methods. Ручная запись этих заголовков отклоняется, чтобы исключить неоднозначное HTTP framing.

Ошибки не проглатываются

Исключение из callback возвращается в Node.js как исходная ошибка; текущая request/socket sequence останавливается, а затронутый wrapper инвалидируется.

Частые вопросы

Короткие ответы на вопросы о выборе пакета, runtime-контрактах и production-ограничениях.

Что такое swm-uws?
swm-uws - экспериментальный non-TLS V8 binding для Node.js 22 и 24, совместимый с обычной поверхностью uWebSockets.js App(). Релиз 0.7.3 закрепляет uWebSockets.js 20.69.0, поставляет platform-specific prebuilds и не имеет runtime npm-зависимостей.
Можно ли использовать swm-uws как drop-in замену uWebSockets.js?
Да, для документированной non-TLS App() поверхности пакет можно установить alias-командой uwebsockets.js@npm:@swarmmachina/swm-uws. SSLApp, H3App, compression, SNI и экспериментальные upstream API не поддерживаются и требуют явной миграции.
Какие данные запроса можно использовать после callback?
Сам HttpRequest недействителен после route или upgrade callback, но строки из getMethod(), getUrl(), getQuery(), getHeader() и getParameter() принадлежат JavaScript и могут жить дольше. Для выбранных заголовков с сохранением duplicate/missing semantics создайте RequestPrefetchPlan и вызовите req.prefetch(plan) внутри callback.
Как настроить HTTP-лимиты и таймауты в swm-uws 0.7?
Передайте App({ http: { ... } }) с maxHeaderSize, maxHeaderCount, headersTimeoutMs, keepAliveTimeoutMs, bodyIdleTimeoutMs, minBodyRateBytesPerSec и responseWriteTimeoutMs. Счётчики отказов и activeConnections доступны через app.getHttpTransportStats().
Кому принадлежит память request body в swm-uws?
onData и onDataV2 передают zero-copy ArrayBuffer, который отсоединяется после callback. collectBody(maxSize, callback) возвращает принадлежащий приложению ArrayBuffer или null при превышении лимита до 1 ГиБ; общий бюджет памяти и admission control остаются ответственностью приложения.
Как pause/resume ограничивает upload в swm-uws 0.7.3?
res.pause() останавливает дальнейшее чтение сокета, когда consumer временно не готов к новым данным. Callback всё ещё может увидеть chunks из текущего parser buffer. Вызывайте res.resume() только после освобождения downstream-ёмкости: не вызванный resume больше не маскируется продолжением чтения и оставляет upload под backpressure.
Какие платформы и сетевые функции поддерживает swm-uws?
Поддерживаются Node.js 22/24, Linux x64 с glibc, Windows x64 и macOS arm64/x64. TLS/SSLApp, H3App, permessage-deflate, SNI, Alpine/musl, Linux ARM64 и Windows ARM64 не поддерживаются; TLS завершается перед приложением.

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