Код под задачу.

Четыре небольших примера с командами проверки. Выберите задачу, сохраните файлы и запустите один рецепт за раз.

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

  • Node.js 22.13+ в ветке 22 или Node.js 24 и поддерживаемая swm-uws платформа: macOS arm64/x64, Windows x64, Linux x64 glibc.
  • Во всех примерах используется loopback и порт 3000. Останавливайте текущий процесс через Ctrl+C перед следующим рецептом.
  • Команды проверки рассчитаны на Bash и curl. Для SIGINT/SIGTERM и закрытия логгера перенесите рецепт в ExampleService из быстрого старта.

Подготовить каталог

В пустом каталоге выполните npm init -y, затем установите закреплённые версии. Сохраняйте код с указанными именами .mjs: настройка ESM в package.json не требуется.

ShellТерминал
npm install @swarmmachina/swm-core@5.2.3 @swarmmachina/swm-logs@0.1.1

JSON API с CORS

CORS-helper вызывается до чтения body. При OPTIONS он отвечает на preflight и возвращает true; обычный POST получает CORS-заголовки и JSON-ответ.

Второй терминал: preflight должен вернуть 204, POST вернёт {"received":{"ok":true}}. Разрешён конкретный origin https://app.example. CORS задаёт доступ браузера к ответу; проверку пользователя нужно реализовать отдельно.

JavaScriptjson-cors.mjs
import Server, { cors } from '@swarmmachina/swm-core'

const applyCors = cors({
  origin: 'https://app.example',
  methods: ['POST', 'OPTIONS'],
  allowedHeaders: ['content-type'],
  maxAge: 600
})

const server = new Server({
  host: '127.0.0.1',
  port: 3000,
  ws: null,
  http: {
    maxBodySize: 64 * 1024,
    maxBodyBudget: 8 * 1024 * 1024,
    routes: [
      {
        method: 'any',
        path: '/api/echo',
        handler: async (ctx) => {
          if (applyCors(ctx)) return
          if (ctx.getMethod() !== 'post') {
            ctx.setStatus(405)
            return { error: 'Method not allowed' }
          }
          return { received: await ctx.json() }
        }
      }
    ]
  }
})

await server.listen()
Скачать json-cors.mjs
ShellТерминал
node json-cors.mjs
# Второй терминал:
curl -i -X OPTIONS http://127.0.0.1:3000/api/echo \
  -H 'origin: https://app.example' \
  -H 'access-control-request-method: POST' \
  -H 'access-control-request-headers: content-type'
curl --fail http://127.0.0.1:3000/api/echo \
  -H 'origin: https://app.example' \
  -H 'content-type: application/json' --data '{"ok":true}'

Проверка WebSocket upgrade

Статический DEMO_TOKEN показывает место проверки серверного клиента. Отсутствующий токен не позволяет запустить пример; неверный токен отклоняет upgrade. Заголовок authorization явно сохраняется через prefetchHeaders.

curl проверяет handshake: с правильным токеном ожидается 101 Switching Protocols, без authorization вернётся 403. После успешного upgrade curl завершится по --max-time: соединение остаётся открытым.

Браузерный WebSocket API не позволяет задать произвольный Authorization-заголовок. Для браузера используйте свою сессию и проверку Origin. Замените демонстрационное сравнение реальной аутентификацией перед сетевым использованием.

JavaScriptwebsocket-auth.mjs
import Server from '@swarmmachina/swm-core'

const token = process.env.DEMO_TOKEN
if (!token) throw new Error('Set DEMO_TOKEN before starting the example')

const server = new Server({
  host: '127.0.0.1',
  port: 3000,
  http: null,
  ws: {
    prefetchHeaders: ['authorization'],
    upgradeTimeoutMs: 5_000,
    maxPayloadLength: 16 * 1024,
    maxBackpressure: 64 * 1024,
    closeOnBackpressureLimit: true,
    onUpgrade: (meta) => {
      if (meta.url() !== '/ws') return null
      return meta.headers.authorization === `Bearer ${token}` ? { role: 'demo' } : null
    },
    onMessage: (ctx, message) => ctx.send(ctx.decode(message))
  }
})

await server.listen()
Скачать websocket-auth.mjs
ShellТерминал
DEMO_TOKEN=local-demo node websocket-auth.mjs
# Второй терминал:
curl --http1.1 --max-time 2 -i http://127.0.0.1:3000/ws \
  -H 'connection: Upgrade' -H 'upgrade: websocket' \
  -H 'sec-websocket-version: 13' \
  -H 'sec-websocket-key: dGhlIHNhbXBsZSBub25jZQ==' \
  -H 'authorization: Bearer local-demo'

Потоковый upload в файл

Сохраните оба файла рядом. UploadSink владеет счётчиком активных загрузок: допускает два потока, а лишнему запросу отвечает 503. Каждый файл получает случайное имя; при ошибке частичный файл удаляется.

bodyStream() создаётся до первого await и передаётся в pipeline(). prefetch выключен, один upload ограничен 8 МиБ. Проверка вернёт 201 и id сохранённого файла в ./uploads.

Streaming обходит maxBodyBudget. Лимит параллелизма относится только к этому процессу; общий объём хранилища, квоты пользователя и очистку успешно загруженных файлов нужно задать отдельно.

JavaScriptupload-sink.mjs
import { randomUUID } from 'node:crypto'
import { createWriteStream } from 'node:fs'
import { rm } from 'node:fs/promises'
import { join } from 'node:path'
import { pipeline } from 'node:stream/promises'

export default class UploadSink {
  #directory
  #active = 0

  constructor(directory) {
    this.#directory = directory
  }

  async accept(ctx) {
    if (this.#active >= 2) {
      ctx.setStatus(503)
      return { error: 'Upload capacity reached' }
    }

    const upload = ctx.bodyStream()
    const id = randomUUID()
    const path = join(this.#directory, id)
    this.#active += 1

    try {
      await pipeline(upload, createWriteStream(path, { flags: 'wx' }))
      ctx.setStatus(201)
      return { id }
    } catch (error) {
      await rm(path, { force: true })
      throw error
    } finally {
      this.#active -= 1
    }
  }
}
Скачать upload-sink.mjs
JavaScriptupload.mjs
import { mkdir } from 'node:fs/promises'
import Server from '@swarmmachina/swm-core'
import UploadSink from './upload-sink.mjs'

await mkdir('./uploads', { recursive: true })
const uploads = new UploadSink('./uploads')
const server = new Server({
  host: '127.0.0.1',
  port: 3000,
  ws: null,
  http: {
    prefetch: false,
    maxStreamBodySize: 8 * 1024 * 1024,
    routes: [{ method: 'post', path: '/upload', handler: (ctx) => uploads.accept(ctx) }]
  }
})

await server.listen()
Скачать upload.mjs
ShellТерминал
node upload.mjs
# Второй терминал:
curl --fail http://127.0.0.1:3000/upload --data-binary @upload.mjs

Request ID и структурированные логи

Генерируйте requestId на сервере, добавляйте его в child logger и возвращайте через x-request-id. Пример пишет только метод и путь; body, cookies и входящие credentials в логи не попадают.

curl покажет одинаковый requestId в заголовке и JSON-ответе, а терминал сервера выведет NDJSON-запись с тем же значением. redaction настроена для верхнеуровневых authorization и password; вложенные поля требуют собственных путей.

JavaScriptrequest-logging.mjs
import { randomUUID } from 'node:crypto'
import Server from '@swarmmachina/swm-core'
import Logger from '@swarmmachina/swm-logs'

const logger = new Logger({
  bindings: { service: 'api' },
  redact: ['authorization', 'password']
})
const server = new Server({
  host: '127.0.0.1',
  port: 3000,
  ws: null,
  http: {
    onRequest: (ctx) => {
      const requestId = randomUUID()
      const log = logger.child({ requestId })
      ctx.setHeader('x-request-id', requestId)
      log.info({ method: ctx.getMethod(), path: ctx.getUrl() }, 'request')
      return { requestId }
    }
  }
})

await server.listen()
Скачать request-logging.mjs
ShellТерминал
node request-logging.mjs
# Второй терминал:
curl -i http://127.0.0.1:3000/hello

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

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