swm-uws is an experimental non-TLS V8 binding for Node.js 22 and 24 that is compatible with the regular uWebSockets.js App() surface. Release 0.7.3 pins uWebSockets.js 20.69.0, ships platform-specific prebuilds, and has no runtime npm dependencies.

Can swm-uws replace uWebSockets.js as a drop-in package?

Yes, for the documented non-TLS App() surface you can install the uwebsockets.js@npm:@swarmmachina/swm-uws alias. SSLApp, H3App, compression, SNI, and experimental upstream APIs are unsupported and require an explicit migration.

Which request data can outlive the route callback?

HttpRequest itself expires after the route or upgrade callback, but strings returned by getMethod(), getUrl(), getQuery(), getHeader(), and getParameter() are JavaScript-owned and may be retained. For selected headers with duplicate and missing-value semantics, compile a RequestPrefetchPlan and call req.prefetch(plan) inside the callback.

How do I configure HTTP limits and timeouts in swm-uws 0.7?

Pass App({ http: { ... } }) with maxHeaderSize, maxHeaderCount, headersTimeoutMs, keepAliveTimeoutMs, bodyIdleTimeoutMs, minBodyRateBytesPerSec, and responseWriteTimeoutMs. Read rejection counters and activeConnections through app.getHttpTransportStats().

Which platforms and network features does swm-uws support?

It supports Node.js 22/24, Linux x64 with glibc, Windows x64, and macOS arm64/x64. TLS/SSLApp, H3App, permessage-deflate, SNI, Alpine/musl, Linux ARM64, and Windows ARM64 are unsupported; terminate TLS before the application.

swm-uws: native uWebSockets binding for Node.js

Installation and quick start

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, and the App / us_listen_socket_close named imports are available.
app.close() is idempotent and closes active HTTP and WebSocket contexts.
The complete TypeScript surface is declared in lib/index.d.ts; defineHttpHandler and defineWebSocketBehavior type extracted JavaScript callbacks.
In v0.7.3, res.pause() stops further socket reads so a slow consumer does not accumulate an upload; res.resume() explicitly restores delivery. The current parser buffer can still deliver chunks it already received.

Supported surface

HTTP routing: get, post, put, patch, del, options, head, connect, trace, and any.
Streaming: write, tryEnd, onWritable, onData, collectBody, pause/resume, and cork.
WebSocket: Lifecycle callbacks, sends, fragmented sends, ping, topics, and pub/sub.
Network addresses: Remote and PROXY protocol addresses, ports, listen options, and Unix sockets.
HTTP transport policy: Per-App header limits, phase-specific timeouts, a minimum body rate, and getHttpTransportStats() counters.
Selective request prefetch: RequestPrefetchPlan normalizes a header selection once, and req.prefetch() returns an owned snapshot of only those fields.
Optional fast paths: capabilities() reports beginWrite, collectBody, httpTransportConfig, requestPrefetch, responseBatch, and requestPause.
Security contracts: The binding validates framing headers, preserves original callback failures, and prevents WebSocket user data from shadowing wrapper methods.
Explicit boundaries: SSLApp/TLS, H3App, permessage-deflate, SNI, and experimental KV/timer helpers are not implemented.

Runtime and platforms

Environment	Status	Note
Node.js 22 / 24	Supported	Prebuilds are released for supported ABIs.
Linux x64 + glibc	Supported	Portable generic x86-64 build.
Windows x64	Supported	A native build is included in the package.
macOS arm64 / x64	Supported	Apple Silicon and Intel are supported.
Linux ARM64 / Windows ARM64	Unsupported	There are no current prebuilds.
Alpine / musl	Unsupported	A glibc environment is required.
TLS / permessage-deflate	Disabled	Terminate TLS in front of the application.

API map

TemplatedApp

Routes, listen operations, WebSocket behavior, and 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, selective header prefetch, and streamed responses.

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

WebSocket

Messages, fragments, backpressure, and topics.

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

Module helpers

JavaScript callback typing, binding metadata, and listener control.

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

Complete signatures, types, and examples are available in the source repository README and TypeScript declarations.

Lifetime and memory ownership

The binding stays close to native uWS, so wrapper and buffer lifetimes are part of the API contract.

Do not retain HttpRequest

The wrapper is valid only inside a route or upgrade callback. Individual get* methods return owned JavaScript strings; for selected headers with duplicate and missing-value semantics, call req.prefetch() with a precompiled RequestPrefetchPlan.

Configure transport policy per App

App({ http }) accepts header limits, phase-specific timeouts, and a minimum body rate. getHttpTransportStats() exposes activeConnections and rejection counters without scanning connections.

Zero-copy requires discipline

onData and onDataV2 receive a zero-copy ArrayBuffer that is detached after the callback. Copy a chunk if it is needed later.

Pause requires resume

res.pause() stops further socket reads, although callbacks can still receive chunks already present in the current parser buffer. Call res.resume() only when the consumer is ready for more input; otherwise the upload remains under backpressure.

Owned body

collectBody(maxSize, callback) accepts a 0..1 GiB byte limit and returns an application-owned ArrayBuffer, or null when exceeded. A global memory limit remains the application’s responsibility.

Extending response lifetime

A Response remains valid after the route callback only when onData, onDataV2, onWritable, collectBody, or onAborted is registered.

Terminal callbacks

Response and WebSocket wrappers are already invalid inside onAborted and close callbacks respectively.

Framing belongs to the binding

Response methods set Content-Length and Transfer-Encoding. Writing either header manually is rejected to prevent ambiguous HTTP framing.

Callback failures remain visible

A callback exception reaches Node.js as the original error; the current request or socket sequence stops and the affected wrapper is invalidated.

Common questions

Concise answers about package selection, runtime contracts, and production constraints.

What is swm-uws?
swm-uws is an experimental non-TLS V8 binding for Node.js 22 and 24 that is compatible with the regular uWebSockets.js App() surface. Release 0.7.3 pins uWebSockets.js 20.69.0, ships platform-specific prebuilds, and has no runtime npm dependencies.
Can swm-uws replace uWebSockets.js as a drop-in package?
Yes, for the documented non-TLS App() surface you can install the uwebsockets.js@npm:@swarmmachina/swm-uws alias. SSLApp, H3App, compression, SNI, and experimental upstream APIs are unsupported and require an explicit migration.
Which request data can outlive the route callback?
HttpRequest itself expires after the route or upgrade callback, but strings returned by getMethod(), getUrl(), getQuery(), getHeader(), and getParameter() are JavaScript-owned and may be retained. For selected headers with duplicate and missing-value semantics, compile a RequestPrefetchPlan and call req.prefetch(plan) inside the callback.
How do I configure HTTP limits and timeouts in swm-uws 0.7?
Pass App({ http: { ... } }) with maxHeaderSize, maxHeaderCount, headersTimeoutMs, keepAliveTimeoutMs, bodyIdleTimeoutMs, minBodyRateBytesPerSec, and responseWriteTimeoutMs. Read rejection counters and activeConnections through app.getHttpTransportStats().
Who owns request body memory in swm-uws?
onData and onDataV2 expose a zero-copy ArrayBuffer that is detached after the callback. collectBody(maxSize, callback) returns an application-owned ArrayBuffer or null above a limit of up to 1 GiB; aggregate memory budgeting and admission control remain application responsibilities.
How does pause/resume bound an upload in swm-uws 0.7.3?
res.pause() stops further socket reads when the consumer is temporarily unable to accept input. A callback can still receive chunks already in the current parser buffer. Call res.resume() only after downstream capacity is available: an omitted resume is no longer masked by continued reads and leaves the upload under backpressure.
Which platforms and network features does swm-uws support?
It supports Node.js 22/24, Linux x64 with glibc, Windows x64, and macOS arm64/x64. TLS/SSLApp, H3App, permessage-deflate, SNI, Alpine/musl, Linux ARM64, and Windows ARM64 are unsupported; terminate TLS before the application.

Drop-in alias for uWebSockets.js

If an application uses the supported regular App() surface, install the package under the original name. SSLApp, H3App, compression, SNI, and experimental APIs require an explicit migration.

Shellinstall alias

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

JavaScriptserver.js

// The original import stays unchanged
import uWS from 'uwebsockets.js'

Need request contexts, routing, body limits, and graceful shutdown?Open swm-core