Первый сервис.

Один процесс, два протокола и явный владелец ресурсов. Соберём локальный сервис с /health, JSON echo и WebSocket, затем проверим его из второго терминала.

Перед запуском

  • 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 как зависимость.

ShellТерминал
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.

JavaScriptservice.mjs
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()
    }
  }
}
Скачать service.mjs

Запустить процесс

Сохраните main.mjs рядом с service.mjs. При SIGINT или SIGTERM сервер получает до пяти секунд на завершение запросов и соединений, затем закрывается логгер.

JavaScriptmain.mjs
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()
}
Скачать main.mjs
ShellПервый терминал
node main.mjs

Проверить HTTP и WebSocket

Сохраните проверку в check-websocket.mjs и выполните команды во втором терминале. Встроенный WebSocket-клиент Node.js не требует отдельного пакета.

Ожидаемый результат: /health возвращает {"ok":true}, /echo возвращает переданный объект в received, WebSocket печатает hello. В первом терминале появятся NDJSON-записи со служебным контекстом и requestId.

JavaScriptcheck-websocket.mjs
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
})
Скачать check-websocket.mjs
ShellВторой терминал
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 закрывается после сервера. Доставку во внешнее хранилище и её срок завершения определяет приложение.

Исходники и версии

swm-core 5.2.3 · README swm-logs 0.1.1 · README