Перед запуском
- Node.js 22.13+ в ветке 22 или Node.js 24. swm-logs 0.1.1 пока не поддерживает Node.js 26.
- macOS arm64/x64, Windows x64 или Linux x64 с glibc. Alpine/musl и Linux ARM64 не поддерживаются нативным транспортом.
- Пример использует native ESM: файлы .mjs работают без изменения type в package.json.
Установить пакеты
Создайте отдельный каталог. Версии закреплены, чтобы пример оставался воспроизводимым. swm-core установит свой нативный транспорт swm-uws как зависимость.
mkdir swm-quick-start
cd swm-quick-start
npm init -y
npm install @swarmmachina/swm-core@5.2.3 @swarmmachina/swm-logs@0.1.1Создать сервис
Сохраните код в service.mjs. Класс ExampleService владеет Server и корневым Logger. stop() возвращает один Promise: повторный сигнал не запускает второе завершение.
JSON-reader создаётся сразу в handler, до первого await. WebSocket доступен анонимно только на /ws; сервер слушает loopback. Это локальный учебный endpoint.
import { randomUUID } from 'node:crypto'
import Server from '@swarmmachina/swm-core'
import Logger from '@swarmmachina/swm-logs'
export default class ExampleService {
#server
#logger
#stopPromise
constructor({ port = 3000 } = {}) {
this.#logger = new Logger({ bindings: { service: 'quick-start' } })
this.#server = new Server({
host: '127.0.0.1',
port,
http: {
maxBodySize: 64 * 1024,
maxBodyBudget: 8 * 1024 * 1024,
requestTimeoutMs: 10_000,
onError: (event, error) => this.#logger.error({ err: error, path: event.url }),
routes: [
{ method: 'get', path: '/health', handler: () => ({ ok: true }) },
{
method: 'post',
path: '/echo',
handler: async (ctx) => {
const log = this.#logger.child({ requestId: randomUUID() })
const body = await ctx.json()
log.info('echo received')
return { received: body }
}
}
]
},
ws: {
maxPayloadLength: 16 * 1024,
maxBackpressure: 64 * 1024,
closeOnBackpressureLimit: true,
onUpgrade: (meta) => (meta.url() === '/ws' ? {} : null),
onMessage: (ctx, message) => ctx.send(ctx.decode(message)),
onError: (_ctx, error) => this.#logger.error(error)
}
})
}
async start() {
await this.#server.listen()
this.#logger.info('HTTP and WebSocket ready on 127.0.0.1')
}
stop() {
this.#stopPromise ??= this.#shutdown()
return this.#stopPromise
}
async #shutdown() {
try {
await this.#server.shutdown(5_000)
} finally {
await this.#logger.close()
}
}
}Запустить процесс
Сохраните main.mjs рядом с service.mjs. При SIGINT или SIGTERM сервер получает до пяти секунд на завершение запросов и соединений, затем закрывается логгер.
import ExampleService from './service.mjs'
const service = new ExampleService()
try {
await service.start()
for (const signal of ['SIGINT', 'SIGTERM']) {
process.once(signal, () => {
void service.stop().catch((error) => {
console.error(error)
process.exitCode = 1
})
})
}
} catch (error) {
console.error(error)
process.exitCode = 1
await service.stop()
}node main.mjsПроверить HTTP и WebSocket
Сохраните проверку в check-websocket.mjs и выполните команды во втором терминале. Встроенный WebSocket-клиент Node.js не требует отдельного пакета.
Ожидаемый результат: /health возвращает {"ok":true}, /echo возвращает переданный объект в received, WebSocket печатает hello. В первом терминале появятся NDJSON-записи со служебным контекстом и requestId.
const socket = new WebSocket('ws://127.0.0.1:3000/ws')
const deadline = setTimeout(() => {
socket.close()
process.exitCode = 1
}, 5_000)
socket.addEventListener('open', () => socket.send('hello'))
socket.addEventListener('message', (event) => {
console.log(event.data)
clearTimeout(deadline)
socket.close()
})
socket.addEventListener('error', () => {
clearTimeout(deadline)
process.exitCode = 1
})curl --fail http://127.0.0.1:3000/health
curl --fail http://127.0.0.1:3000/echo \
-H 'content-type: application/json' \
--data '{"hello":"world"}'
node check-websocket.mjsСледующий шаг
Остановите процесс через Ctrl+C. Для сетевого сервиса добавьте проверку пользователя и Origin при WebSocket upgrade, настройте TLS на reverse proxy и подберите лимиты под свою нагрузку.
- В примере: тело запроса до 64 КиБ, суммарный body budget 8 МиБ, timeout 10 секунд.
- WebSocket: сообщение до 16 КиБ, очередь отправки до 64 КиБ, медленные клиенты закрываются при достижении лимита.
- Logger закрывается после сервера. Доставку во внешнее хранилище и её срок завершения определяет приложение.