swm-core: HTTP and WebSocket server for Node.js

Installation and quick start

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

Keep synchronous handlers synchronous: use the Promise path only when the handler actually awaits work.
http.onRequest and http.routes are mutually exclusive. An empty http: {} configuration returns a predictable 404.
HTTP and WebSocket can be enabled independently; at least one protocol must be configured.

What the server provides

Native transport: HTTP and WebSocket traffic passes through @swarmmachina/swm-uws without an intermediate JavaScript transport layer.
Two routing APIs: Use a universal onRequest handler or declarative method/path routes with :param and wildcard /* segments.
Memory control: HttpContext pools, separate HTTP/WS limits, maxBodyBudget, and lazy request body reads.
Streaming and backpressure: stream, startStreaming, tryEnd, onWritable, and a numeric WebSocket send status.
Connection control: Pub/sub, connectionKey addressing, sendTo, graceful close, and forced termination.
Shutdown: shutdown(timeout) waits for active connections; close() stops the server immediately.

Runtime and platforms

Environment	Status	Note
Node.js 22 / 24	Supported	Other major versions are rejected by the engines constraint.
Linux x64 + glibc	Supported	Use bookworm/slim-based container images.
Windows x64	Supported	A prebuilt native binary is included.
macOS arm64 / x64	Supported	Apple Silicon and Intel are supported.
Linux ARM64 / Windows ARM64	No build	These targets are not in the current prebuild matrix.
Alpine / musl	Unsupported	Use a glibc-based image.
TLS / permessage-deflate	Disabled	Terminate TLS in front of the application.

API map

Server

Lifecycle, pub/sub, and addressable WebSocket connections.

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

HttpContext

Request data, responses, body readers, and streaming.

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

Operations on one WebSocket connection.

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

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

Body lifetime, limits, and backpressure

swm-core deliberately keeps cost and data lifetime visible. These rules matter for correct production code.

Read lazy bodies before the first await

In the default mode, call ctx.body(), buffer(), text(), or json() before the first asynchronous operation. Otherwise uWS body events may arrive before a reader is registered.

Use prefetch for asynchronous auth

Enable prefetch globally or per route when authorization or database work must finish before reading the body. Bytes are collected early while JSON parsing remains lazy.

Bound aggregate memory

maxBodySize limits one request; maxBodyBudget limits all bodies being collected. Budget exhaustion returns 503, while a per-request limit returns 413.

Check the send status

WSContext.send() returns 1 on success, 0 on backpressure, and 2 when a message is dropped because of a limit.

Do not retain HttpContext

HttpContext is reused between requests. WSContext lives for the connection, but must not be used after onClose.

When to use the low-level binding

swm-core fits most services. Move to swm-uws when you need direct compatibility with the regular uWebSockets.js App() API and are prepared to manage request and response object lifetimes yourself.

JavaScripttransport-choice.js

// High-level server
import Server from '@swarmmachina/swm-core'

// Low-level binding
import uWS from '@swarmmachina/swm-uws'

Need the low-level uWebSockets.js API without server abstractions?Open swm-uws